<!--conf <?xml version="1.0"?>
<article include="true"><title>User Guide</title><keywords></keywords><modifications/><samples/></article>
--><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
	<title>DHTML Tree v.1.5 guide and samples</title>
	<meta http-equiv="content-type" content="text/html;charset=UTF-8">
	<link rel="STYLESHEET" type="text/css" href="common/styles.css">
</head>

<body>

<h2><a href="http://www.dhtmlx.com/docs/products/dhtmlxTree/index.shtml" target="_top" title="Visit javascript tree home page">dhtmlXTree</a> Guide and Samples</h2>
<div class="block">
<!---  --->
	<a name="mf"><h3 >Main features</h3
	></a><div style="display:show" class="block">
		<li>Multibrowser/Multiplatform support </li>
		<li>Full controll with JavaScript</li>
		<li>Dynamic loading</li>
		<li>XML support</li>
		<li>Dynamic rendering (Smart XML parsing) for big trees</li>
		<li>drag-&-drop (within one tree, between trees, between frames) </li>
		<li>checkboxes (two/three states)</li> 
		<li>customizable icons (with javascript or xml) </li>
		<li>context menu (integration with dhtmlxMenu)</li>
		<li>user data for nodes</li>
		<li>multi-line tree items</li>
		<li>high stability</li>
		<li>Macromedia Cold Fusion support</li>
		<li>JSP support</li>
		<li>ASP.NET support</li>
	</div>
	
	<a name="browsers"><h3 >Supported browsers</h3
	></a><div style="display:show" class="block">
		<li>IE 5.5 and above</li>
		<li>Mac OS X Safari</li>
		<li>Mozilla 1.4 and above</li>
		<li>FireFox 0.9 and above</li>
		<li>Opera (Xml loading depends on browser version)</li>
	</div>

	<h3 >Working with dhtmlXTree</h3
	><div style="display:show" class="block">
<!--- Initialize object on page --->
		<a name="init"><h4 >在页面上初始化对象</h4
		></a><div class="block">
<XMP>
<div id="treeBox" style="width:200;height:200"></div>
<script>
	tree=new dhtmlXTreeObject(document.getElementById('treeBox'),"100%","100%",0);
	tree.setImagePath("gfx/");
	tree.enableCheckBoxes(false);
	tree.enableDragAndDrop(true);
</script>
</XMP>
		构造函数参数:
			<li>object to attach tree to (should be loaded before calling constructor)</li>
			<li>树宽度</li>
			<li>树高度</li>
			<li>树根目录的标识符(根节点id)</li><br>
		指定树的其他参数:
			<li>setImagePath(url) - 指定树图标所在的文件夹路径</li>
			<li>enableCheckBoxes(mode) - 启用/禁用树的复选框 (默认启用)</li>
			<li>enableDragAndDrop(mode) - 启用/禁用树的拖拽功能</li>
		</div>
<!--- Set Additional init parameters --->	
		<a name="handlers"><h4 >事件绑定</h4
		></a><div class="block">
		自 1.5 版本起,dhtmlxTree 支持新的事件绑定方式-通过attachEvent方法.因此,要设置事件,你需要了解事件名称并定义Function与之绑定.<br>事件可用的名称在<a href="events.html">这里</a>.
		通过attachEvent绑定事件,你可以参考本文.<br>
		Since version 1.5 dhtmlxTree supports new way of setting event handlers - with attachEvent method. 
		So, to set event handler you need to know event name and define function which will be handler itself.<br>
		Event names available <a href="events.html">here</a>. Inside event handlers set with attachEvent, you can refer to tree object through <i>this</i>
<XMP>
<div id="treeBox" style="width:200;height:200"></div>
<script>
	tree=new dhtmlXTreeObject(document.getElementById('treeBox'),"100%","100%",0);
	...
	//tree.setOnClickHandler(onNodeSelect);//old way of setting event handlers
	tree.attachEvent("onClick",onNodeSelect)//set function object to call on node select
	//see other available event handlers in API documentation
	function onNodeSelect(nodeId){
		...
	}
</script>
</XMP>	大多数情况下,事件可以获取一些参数的值,详细的参数信息,请参考 Events 文档.<br>
		In most cases functions specified as event handler gets some values with the arguments. For details about passed arguments please refer to <a href="events.html">Events documentation</a>.<br>
		</div>
<!--- Adding nodes with Script --->
		<a name="scriptadd"><h4 >添加节点Adding nodes with Script</h4
		></a><div class="block">
<XMP>
<script>
	tree=new dhtmlXTreeObject('treeBox',"100%","100%",0);
	...
	tree.insertNewChild(0,1,"New Node 1",0,0,0,0,"SELECT,CALL,TOP,CHILD,CHECKED");
	tree.insertNewNext(1,2,"New Node 2",0,0,0,0,"CHILD,CHECKED");
</script>
</XMP>	
		<li>第4-7个参数值为0,这意味着将使用默认值.<br>0s passed to the function for arguments 4-7 (function to call on select, images) mean use default values for them</li>
		<li>最后一个参数为以逗号分隔的字符串,可能为以下值<br>Last argument is a comma delimited string of following possible value (upper case only):</li>
			<li type="circle">SELECT - 移动选择的节点后插入(move selection to this node after inserting)</li>
			<li type="circle">CALL - 执行 on select 事件(call function on select)</li>
			<li type="circle">TOP - 在顶端位置插入节点(add node to the top position) </li>
			<li type="circle">CHILD - 节点有子节点(node has children)</li>
			<li type="circle">CHECKED - 复选框为选择状态(如果存在)(checkbox is checked (if exists))</li>
		</div>
<!--- Using XML --->
		<a name="xmlload"><h4 >加载xml中的数据Loading data with XML</h4
		></a><div class="block">
<XMP>
<script>
	tree=new dhtmlXTreeObject('treeBox',"100%","100%",0);
	tree.setXMLAutoLoading("http://127.0.0.1/xml/tree.xml");
	tree.loadXML("http://127.0.0.1/xml/tree.xml");//load root level from xml
</script>
</XMP>	
		<li>ID of opened node (as id url parameter) will be added to URL specified in  initXMLAutoLoading(url) during the call</li>
		<li>No additional ID is added to the url specified in loadXML(url) method during the call</li>
		<li>Using loadXML() without parameters you load url specified in initXMLAutoLoading(url) method</li>
<XMP>
XML Syntax:
<?xml version='1.0' encoding='iso-8859-1'?>
<tree id="0">
	<item text="My Computer" id="1" child="1" im0="my_cmp.gif" im1="my_cmp.gif" im2="my_cmp.gif" call="true" select="yes">
		<userdata name="system">true</userdata>
		<item text="Floppy (A:)" id="11" child="0"  im0="flop.gif" im1="flop.gif" im2="flop.gif"/>
		<item text="Local Disk (C:)" id="12" child="0"  im0="drv.gif" im1="drv.gif" im2="drv.gif"/>
	</item>
	<item text="Recycle Bin" id="4" child="0" im0="recyc.gif" im1="recyc.gif" im2="recyc.gif"/>
</tree>
</XMP>	
<br>
In <strong>PHP</strong> script use the following code for page header:<br>
<xmp>
<?php
	if ( stristr($_SERVER["HTTP_ACCEPT"],"application/xhtml+xml") ) {
  		header("Content-type: application/xhtml+xml"); } else {
  		header("Content-type: text/xml");
	}
	echo("<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>\n"); 
?>
</xmp>
<br>
		<strong>&lt;tree&gt;</strong> node is mandatory. It specifies the parent of loading block of data. According to this its id parameter specifies the ID oth that parent. 
		To load root level you need to specify the ID you used when created tree object: new myObjTree(boxObject,width,height,<b>0</b>) <br>
		
		<strong>&lt;item&gt;</strong> can contain subitems (in order to load more than one level at once) or not. It also can contain <strong>&lt;itemtext&gt;</strong> tag (only PRO edition), which can be used to add some HTML to item label (attribute <em>text</em> should be skipped then):<br>
<XMP>
<item id="123">
	<itemtext><![CDATA[<font color="red">Label</font>]]></itemtext>
</item>
</XMP>	
		
		
		必须参数(Mandatory parameters for this tag are):<br>
			<li>text - 节点的文本(label of the node)</li>
			<li>id - 节点的id(id of the node)</li>
		可选参数(Optional parameters for this tag are):<br>
			<li>tooltip - 节点的提示(tooltip for the node)</li>
			<li>im0 - 无子节点时的节点图片(image for node without children (tree will get images from the path specified in setImagePath(url) method))</li>
			<li>im1 - 打开状态的节点图片(image for opened node with children)</li>
			<li>im2 - 关闭状态的节点图片(image for closed node with children)</li>
			<li>aCol - 未选择时的颜色(colour of not selected item)</li>
			<li>sCol - 选择时的颜色(colour of selected item)</li>
			<!--- <li>top - </li> --->
			<li>select - 选择节点加载(select node on load (any value))</li>
			<li>style - 节点文字样式(node text style)</li>
			<li>open - 显示节点打开(show node opened (any value))</li>
			<li>call - 选择时调用(call function on select(any value))</li>
			<li>checked - 选定(如果存在)check checkbox if exists(any value)</li>
			<li>child - 有子节点(1)或没子节点(0)spec. if node has children (1) or not (0)</li><br>
			<li>imheight - 图标高度height of the icon</li>
			<li>imwidth - 图标宽度width of the icon</li>
			<li>topoffset - offset of the item from the node above</li>
			<li>radio - if non empty, then children of this node will have radiobuttons</li>
<br><br>
To set <strong>userdata</strong> directly within XML use <strong>&lt;userdata&gt;</strong><br>
		It has just one parameter: <br>
			<li>name</li><br>
		and value to specify userdata value			
		</div>
<!--- Setting custom icons to nodes --->
		<a name="iconscust"><h4 >Setting custom icons to nodes</h4
		></a><div class="block">
			There are two ways to set custom icons for the node. And it depends on the way you add items.<br>
			<em>Important:</em> tree will get images for the nodes from the path specified in setImagePath(url) method.<br><br>
			
			Javascript way. Using arguments of insertNewChild(...) or insertNewNext(...) methods:
<XMP>
<script>
	var im0 = "doc.gif";//icon to show if node contains no children
	var im1 = "opened.gif";//if node contains children and opened
	var im2 = "closed.gif";//if node contains children and closed
	tree.insertNewItem(0,1,"New Node 1",0,im0,im1,im2);
	tree.insertNewNext(1,2,"New Node 2",0,"txt.gif","opened.gif","closed.gif");
</script>
</XMP>	
			XML way. Using parameters of &lt;item&gt; tag:
<XMP>
<?xml version='1.0' encoding='iso-8859-1'?>
<tree id="0">
	<item text="My Computer" id="1" child="1" im0="doc.gif" im1="my_opened.gif" im2="my_closed.gif">
</tree>
</XMP>	
			<li>im0 - image for node without children (tree will get images from the path specified in setImagePath(url) method)</li>
			<li>im1 - image for opened node with children</li>
			<li>im2 - image for closed node with children</li>
		</div>
<!--- Dynamical loading --->		
		<a name="dyntree"><h4 >构建动态树</h4
		></a><div class="block">
		如果您的树应包含大量的节点（或者你根本不想再浪费时间载入隐藏的节点）,最好是当需要时在加载.而不是一次加载全部.为此,我们使用xml动态加载树层次.<br>
		见<a href="#xmlload">加载xml数据</a>章节或从我们的知识库<a href="dyn_loading.html">“动态加载dhtmlxTree v.1.x ”</a>获取更详细的资料。<br>
		If your tree should contain large amount of nodes (or you simply do not want to waste time loading hidden nodes), it would be better to load them on demand, not at once. 
		For this purpose we made the tree to load levels dynamically using XML.  <br>
		See chapter <a href="#xmlload">"Loading data with XML"</a><br>
		or for more details <a href="dyn_loading.html">"Dynamical Loading in dhtmlxTree v.1.x"</a> article from our Knowledge Base. 
		</div>
		
		
		
		<a name="nodesman"><h4 >操作节点</h4
		></a><div class="block">
	有几个操作节点方法的例子:
<XMP>
<script>
	tree=new dhtmlXTreeObject('treeboxbox_tree',"100%","100%",0);
	...
	var sID = tree.getSelectedItemId();//get id of selected node
	tree.setLabel(sID,"New Label");//change label of selecte node
	tree.setItemColor(sID,'blue','red');//set colors for selected node's label (for not selected state and for selected state)
	tree.openItem(sID);//expand selected node
	tree.closeItem(sID);//close selected node
	tree.changeItemId(sID,100);//change id of selected node to 100
	alert("This node has children: "+tree.hasChildren(100));//show alert with information if this node has children
</script>
</XMP>	
		</div>
		
<a name="serialize"><h4 >序列是</h4></a><div class="block">
Serialization methods allows getting tree in xml representation (xml string). Various levels of serializations define the number of tree parameters reflected in resulting XML:<br>

<XMP>
<script>
	tree.setSerializationLevel(userDataFl,itemDetailsFl);
	var myXmlStr = tree.serializeTree();

</script>
</XMP>	
<li>no parameters - id,open,select,text,child</li>
<li>userDataFl true - userdata</li>
<li>itemDetailsFl true - im0,im1,im2,acolor,scolor,checked,open</li>
</div>
	
	
<a name="tooltip"><h4 >Tooltips</h4></a><div class="block">
There are three ways to set tooltip for the node:<br>
	<li>Use node label ("text" attribute of item node) as tooltip - enableAutoTooltips(mode) - <em>false</em> by default</li>
	<li>Use "tooltip" attribute of item node for tooltip (it is used by default if this attribute was specified)</li>
	<li>setItemText(itemId,newLabel,<strong>newTooltip</strong>)</li>
</div>

<a name="move"><h4 >移除节点</h4></a><div class="block">
To move Item programaticaly developer can use the following ways:	<br>
<br>
<strong>To move up/down/left:</strong>
<XMP>
	tree.moveItem(nodeId,mode) 
</XMP>
<i>mode</i> possible values are:<br>
<li>"down" - move node down in list of nodes (do not pay attention on hierarchy)</li>
<li>"up" - move node up in list of nodes</li>
<li>"left" - move node up in hierarchy</li>
<br><br>

<strong>To move directly into position (within tree)</strong>
<XMP>
	tree.moveItem(nodeId,mode,targetId) 
</XMP>
<i>mode</i> possible values are:<br>
<li>"item_child" - place node as child of node specified in third argument</li>
<li>"item_sibling" - place node as sibling of node specified in third argument</li><br>
<i>targetId</i> - id of target node.
<br><br>	

<strong>To move node into position (to another tree)</strong>
<XMP>
	tree.moveItem(nodeId,mode,targetId,targetTree) 
</XMP>
<i>mode</i> possible values as above.<br>
<i>targetId</i> - id of target node (in target tree).<br>
<i>targetTree</i> - target tree object<br><br>

<strong>Cut/Paste way</strong><br>
Another way is to use doCut(),doPaste(id) - but this works with selected item only. Developer can also delete node in one place and create it in other (also the way ;-)).<br>
To give users the possibility to move items use drag-n-drop functionlity.
</div>

<a name="counter"><h4 >Items Counter</h4></a><div class="block">
There is a possibility to display item children elements counter with the label of the node. To activate this feature use the following:	
<XMP>
<script>
	tree.setChildCalcMode(mode);
</script>
</XMP>	
Possible modes are:<br>
	<li>"child"  - all childs on this level</li>
	<li>"leafs"  -  all childs without subchilds on this level</li>
	<li>"childrec" - all childs</li>
	<li>"leafsrec" all childs without subchilds</li>
	<li>"disabled" - nothing</li>
<br>
Other related methods:<br>
<strong>_getChildCounterValue(itemId)</strong> - get current counter value<br>
<strong>setChildCalcHTML(before,after)</strong> - html around counter to change default [x]<br>
Use <em>child</em> attribute in xml if you need to set counter value when using dynamical loading.

</div>

<a name="smartxml"><h4 >智能解析XML</h4></a><div class="block">
The idea of Smart XML Parsing is simple - the entire tree structute loaded on client side, but only nodes which should be displayed are rendered. This helps to dramaticaly decrease loading time and general performance of large trees. Plus - in the contrary to Dynamical Loading - entrire tree structure is available for most of script methods (for example Search performed agains all nodes - not only rendered). To activate Smart XML Parsing use the following method:
<XMP>
<script>
	tree.enableSmartXMLParsing(true);//false to disable
</script>
</XMP>	
Smart XML Parsing do not work if tree loaded fully expanded.
</div>
	
<a name="checkbox"><h4 >Checkboxes in tree</h4></a><div class="block">
dhtmlxTree support two or three state checkboxes. Three state checkboxes means: checked/unchecked/some-child-checked (not all).
To enable three state checkboxes use the following method:	 	
<XMP>
<script>
	tree.enableThreeStateCheckboxes(true)//false to disable
</script>
</XMP>	
Using three-state checboxes with smart xml parsing you need to specify third state manually (checked="-1"):
<xmp>
	<item checked="-1" ...>
		<item checked="1" .../>
		<item .../>
	</item>
</xmp>
Checkboxes can be disabled - <strong>disableCheckbox(id,state)</strong><br>
Some node can hide checkboxes - <strong>showItemCheckbox(id,state)</strong> (<strong>nocheckbox</strong> xml attribute)
<br>
Since v.1.4 showItemCheckbox can be aplied to whole tree (use 0 or null as first argument)

</div>		

<a name="radiobut"><h4 >Radiobuttons in tree</h4></a><div class="block">
dhtmlxTree support radiobuttons. To turn them on for the whole tree 	 	
<XMP>
<script>
	tree.enableRadiobuttons(true);
</script>
</XMP>	
<br>
To turn on radiobuttons for some particular node (instead of checkboxes):
<XMP>
<script>
	tree.enableCheckboxes(true);
	tree.enableRadiobuttons(nodeId,true);
</script>
</XMP>	
<br>
By default radibuttons grouped by level, but since v.1.4 it can be set to whole tree:

<XMP>
	tree.enableRadiobuttons(true)
</XMP>

<br>
Checkboxes related API methods and XML attributes are actual for radiobuttons also (taking into account specificity of radiobuttons functionlity). 

</div>		

<a name="dnd"><h4 >Drag-and-drop technics</h4></a><div class="block">
There are three modes of drag-n-drop (set with <strong>setDragBehavior(mode)</strong>):<br>
<li>Drop as child - "child"</li><br>
<li>Drop as sibling - "sibling"</li><br>
<li>Complex mode (both previous are active) - "complex"</li> <br>
Plus two modes of each of them:<br>
<li>1. Common drag-n-drop</li><br>
<li>2. Copy with drag-n-drop - <strong>tree.enableMercyDrag(1/0)</strong></li><br>
All modes can be changed on the fly.<br>
<br>
<h5>Event handlers</h5>
To process drag-n-drop before drop occured use onDrag event handler - <strong>attachEvent("onDrag",func)</strong>. If func doesn't return <em>true</em>, drop will be canceled.<br>
After drop occured there is another event - onDrop - handle it using attachEvent("onDrop",func).<br>
Both event handlers pass 5 parameters into the func object:<br>
<li>id of node which was dragged</li>
<li>id of target node</li>
<li>id of target-before node (if drop as sibling)</li>
<li>tree object source</li>
<li>tree object target</li>
</div>	

<a name="dndifr"><h4 >Drag-and-drop between iframes</h4></a><div class="block">
Drag-n-drop between iframes enabled by default (not supported in Opera 9+ due to browser's limitations). All you need to do additionaly is to insert the following code into the page where no tree exists:<br>
<xmp>
<script src="codebase/dhtmlxcommon.js"></script>
<script>
	new dhtmlDragAndDropObject();
</script>
</xmp>
</div>	

<a name="guide_perf"><h4 >Increasing Performance</h4></a><div class="block">
Taking into account the general low performance of DHTML we introducrd two ways of increasing performance of large trees:<br>
1. <a href="#dyntree">Dynamical Loading</a><br>
2. <a href="#smartxml">Smart XML Parsing</a><br>
3. <a href="#distparse">Distributed Parsing</a><br>
3. <a href="#smartrnd">Smart Rendering</a><br>
Also be sure your tree was organized well - putting a lot of items on one level of the branch makes tree difficalt for visual perception and decrease performance, although <a href="#distparse">Distributed Parsing</a> or <a href="#smartrnd">Smart Rendering</a> can help here. 
</div>	

<a name="context_menu"><h4 >Context Menu</h4></a><div class="block">
There is built in context menu in dhtmlxTree. 
The content of this menu can be set with XML or script. 
For changing context menu content depending on tree item developer can implement function for hidding/showing items of the same menu or associate different menues with different items. 
To enable context menu do the following: 
<XMP>
<script>
//init menu
		aMenu=new dhtmlXContextMenuObject('120',0,"../codebase/imgs/");
		aMenu.menu.loadXML("menu/_context.xml");				
		aMenu.setContextMenuHandler(onMenuClick);
		
//init tree	
		tree=new dhtmlXTreeObject("treeboxbox_tree","100%","100%",0);
		...
		tree.enableContextMenu(aMenu); //link context menu to tree
function onMenuClick(id){
	alert("Menu item "+id+" was clicked");
}
</script>
</XMP>	<br>
<strong>HTTPS compatibility</strong>
<br><br>
For HTTPS compatibility we added two more parameters to context menu constructor:<br>
<li>Images URL</li>
<li>Dummy page URL (url of the page to use for iframes src /now they are empty as iframes are used to make menu be positioned under selectboxes in IE/ in menu to make it compatible with https)		
<XMP>
<script>
//init menu compatible with sHTML
	aMenu=new dhtmlXContextMenuObject('120',0,"imgs/","empty.html");
	...
</script>
</XMP>
</div>	

<a name="refresh"><h4 >Refreshing nodes</h4></a><div class="block">
<li>refreshItems(itemIdList,source) to refresh only items from the itemIdList (not their children)</li>
<li>refreshItem(itemId) - to refresh children of item with itemId. In this case auto loading should be activated.</li>
</div>	

<a name="sort"><h4 >Sorting nodes</h4></a><div class="block">
You can sort nodes in dhtmlxTree Pro (necessary file: dhtmlxtree_sb.js) using follwoing ways:<br>
<strong>Sort by label text (if no custom comparator specified)</strong><br>
<XMP>
	tree.sortTree(nodeId,order,all_levels);
</XMP>
<li><em>nodeId</em> - parent of the level to start sorting from (id of superroot for entire tree) </li>
<li><i>order</i> - sort direction: "ASC"/"DES"</li>
<li><em>all_levels</em> - if true, then all sublevels will be processed as well</li>
<br><br>
<strong>Custom defined sorting</strong><br>
<XMP>
	//define your comparator (in our case it compares second words in label)
	function mySortFunc(idA,idB){
		a=(tree.getItemText(idA)).split(" ")[1]||"";
		b=(tree.getItemText(idB)).split(" ")[1]||"";
		return ((a>b)?1:-1);
	}
	tree = new ...
	//attach your comparator to the tree
	tree.setCustomSortFunction(mySortFunc);
</XMP>
Comparator function gets 2 nodes IDs. Use your tree object there and these IDs to return a comparison result.
<br>
If custome comparator was specified, then tree.sortTree(...) method uses it for sorting.

</div>	

<a name="search"><h4 >Search functionlity</h4></a><div class="block">
Search functionality of dhtmlxTree allows moving focus on node with label fitting searchString mask.<br> 
Has support for Smart XML Parsing.<br><br>
Script syntax:
<XMP>
	tree.findItem(searchString); //find item next to current selection
	tree.findItem(searchString,1,1)//find item previous to current selection
	tree.findItem(searchString,0,1)//search from top
</XMP>
Example of usage is included in Professional Edition package � samples/treeExPro2.html.
</div>	


<a name="multiline"><h4 >Multiline tree items</h4></a><div class="block">
...allows displaying tree items in multiline mode. For now it is recommended to turn tree lines off for better appearance. To enable multiline feature you need to do the following: 
<XMP>
	tree.enableTreeLines(false);
	tree.enableMultiLineItems(true);
</XMP>
Example of usage is included in professional edition package � samples/treeExPro6.html.
</div>	

<a name="g_icons"><h4 >Icons in Tree</h4></a><div class="block">
<h4>Set Icons</h4>
There is a way to set icons for the node explicetly using script (<strong>setItemImage,setItemImage2</strong>) or xml (<strong>im0,im1,im2</strong> attributes of item node):<br>
<li>im0 - item without children</li>
<li>im1 - closed item with children</li>
<li>im2 - opened item with children</li>
<h4>Set Icon Size</h4>
There is a way to set icon size for the whole tree or each node using script or xml:<br>

XML syntax for icon size per each item (optional):
<xmp><item ... imheight="Xpx" imwidth="Xpx"></item></xmp>

Script syntax:
<XMP>
	tree.setIconSize(w,h);//set global icon size
	tree.setIconSize(w,h,itemId)//set icon size for particular item
</XMP>	
</div>	

	</div>

<a name="keyboard"><h4 >Keyboard Navigation</h4></a><div class="block">
By default dhtmlxTree doesn't have keyboard support, but you can add dhtmlxtree_kn.js file to you page
and enable keyboard support with just one javascript command: 
<XMP>
<script  src="../codebase/ext/dhtmlxtree_kn.js"></script>
<script>
	tree.enableKeyboardNavigation(true);
</script>
</XMP>	
Default keys are:<br>
<li>Up arrow - select upper item</li>
<li>Down arrow - select lower item</li>
<li>Right arrow - open item</li>
<li>Left arrow - close item</li>
<li>Enter - call item's action</li><br><br>

But you also can assign your own keys for these:<br>
<XMP>
	tree.assignKeys([["up",104],["down",98],["open",102],["close",100],["call",101]]);
</XMP>	
where "up"/"down"/"open"/"close"/"call" are available actions and numbers are key codes.
</div>

<a name="distparse"><h4 >Distributed Parsing</h4></a><div class="block">
Another way to increase big tree performance which has some levels with 
more than 100-200 nodes per level was introdused in v.1.3 of dhtmlxTree Professional Edition. 
This is  Distributed Parsing. The main advantage is that you get the level visible and 
ready to utilization before it completely parsed.<br>
To enable this functionlity use the following js command:
<XMP>
<script>
	tree.enableDistributedParsing(mode,count,timeout);
</script>
</XMP>	
<strong>Parameters are:</strong>
<li><strong>mode</strong> - mandatory - true/false - enable/disable Distributed Parsing</li>
<li>count - optional - number of nodes in portion</li>
<li>timeout - optional - delay in milliseconds between portions</li><br><br>

This functionaity is fully compatible with <a href="#smartxml">Smart XML Parsing</a>
</div>
	
<a name="error"><h4 >Error handling in dhtmlxTree</h4></a><div class="block">
Some exceptions in dhtmlxTree can be captured and processed.

<xmp>
function myErrorHandler(type, desc, erData){
	alert(erData[0].status)
}
dhtmlxError.catchError("ALL",myErrorHandler);
</xmp>
<strong>Supported Error Types are:</strong><br>
<li>"All"</li>
<li>"LoadXML"</li>
<br><br>
<strong>Handler gets the following params:</strong><br>
<li>type - string (mentioned above)</li>
<li>desc - error description (hardcoded in code)</li>
<li>erData - error related array objects(see below).</li>
<br>
<table width="100%" border="0" style="font-size:12px;" cellspacing="0">
	<tr style="font-weight:bold;">
		<td width="100">Type</td>
		<td>Object(s)</td>
	</tr>
	<tr>
		<td>LoadXML</td>
		<td>[0] - response object</td>
	</tr>
</table>
	
</div>	
</div>
	
	<a name="cftag"><h3 >Cold Fusion Tag for dhtmlXTree</h3
	></a><div class="block">
<XMP>
<cf_dhtmlXTree
	name="tree"
	width="250"
	height="250"
	JSPath="../"
	CSSPath="../"
	iconspath="gfx/"
	xmldoc="tree.xml"
	checkboxes="false"
	dragndrop="true"
	style="background-color:whitesmoke;border:1px solid blue;"
	onSelect="onNodeSelect"
	onDrop="onDropNode">
		...configuration xml...
	</cf_dhtmlXTree>
</XMP>
	<li>name - [optional] name of the tree js object to use in javascript,  if skiped, then name autogenerated</li>
	<li>width - [optional] width of the tree (definitely it sets the with of the tree box, leaving the with of the tree itself by 100%)</li>
	<li>height - [optional] height of the tree</li>
	<li>JSPath - [optional] absolute or relative path to directory which contains tree js files, "js" directory by default</li>
	<li>CSSPath - [optional] absolute or relative path to directory which contains tree css files, "css" directory by default</li>
	<li>iconspath - [optional] absolute or relative path to directory which contains tree icon files, "img" directory by default</li>
	<li>xmldoc - [mandatory for xml loading] url of the xml file used to load levels dynamically</li>
	<li>checkboxes - [optional] show checkboxes (none, twoState, threeState)</li>
	<li>dragndrop - [optional] activate drag-&-drop (true,false)</li>
	<li>style - [optional] style for the tree box</li>
	<li>onSelect - [optional] javascript function to call on node selection</li>
	<li>oncheck - [optional] javascript function to call on node (un)checking</li>
	<li>onDrop - [optional] javascript function to call on node drop</li>
	<li>im1 - [optional] default image used for child nodes</li>
	<li>im2 - [optional] default image used for opened branches</li>
	<li>im3 - [optional] default image used for closed branches</li>			
	<br>
	For description of optional configuration xml - see chapter <em>"Loading data with XML"</em>
	<br><br>
Minimal possible tag syntax with on-page xml:
<XMP>
<cf_dhtmlXTree> 
	<item text="Top node" id="t1" >
		<item text="Child node 1" id="c1" ></item>
		<item text="Child node 2" id="c2" ></item>
	</item>
</cf_dhtmlXTree>	
</XMP>
Minimal possible tag syntax with server-side xml:
<XMP>
<cf_dhtmlXTree 	xmldoc="tree.xml">
</cf_dhtmlXTree>
</XMP>
With images specified:
<XMP>
<cf_dhtmlXTree  
	im1="book.gif" 
	im2="books_open.gif" 
	im3="books_close.gif">
	<item text="Mystery " id="mystery"  open="yes" >
		<item text="Lawrence Block" id="lb" >
			<item text="All the Flowers Are Dying" id="lb_1" />
			<item text="The Burglar on the Prowl" id="lb_2" />
			<item text="The Plot Thickens" id="lb_3" />
			<item text="Grifters Game" id="lb_4" />
			<item text="The Burglar Who Thought He Was Bogart" id="lb_5" />
		</item>
		<item text="Robert Crais" id="rc" >
			<item text="The Forgotten Man" id="rc_1" />
			<item text="Stalking the Angel" id="rc_2" />
			<item text="Free Fall" id="rc_3" />
			<item text="Sunset Express" id="rc_4" />
			<item text="Hostage" id="rc_5" />
		</item>
		<item text="Ian Rankin" id="ir" ></item>
		<item text="James Patterson" id="jp" ></item>
		<item text="Nancy Atherton" id="na" ></item>
	</item>
</cf_dhtmlXTree>
</XMP>
With Events Handlers,Checkboxes and Drag-n-drop:
<XMP>
<cf_dhtmlXTree   
	dragndrop="true"  
	checkboxes="twoState" 
	onSelect="onClick" 
	onCheck="onCheck" 
	onDrop="onDrag">
		<item text="Mystery " id="mystery"  open="yes" >
			<item text="Lawrence Block" id="lb" >
				<item text="All the Flowers Are Dying" id="lb_1" />
				<item text="The Burglar on the Prowl" id="lb_2" />
				<item text="The Plot Thickens" id="lb_3" />
				<item text="Grifters Game" id="lb_4" />
				<item text="The Burglar Who Thought He Was Bogart" id="lb_5" />
			</item>
			<item text="Robert Crais" id="rc" >
				<item text="The Forgotten Man" id="rc_1" />
				<item text="Stalking the Angel" id="rc_2" />
				<item text="Free Fall" id="rc_3" />
				<item text="Sunset Express" id="rc_4" />
				<item text="Hostage" id="rc_5" />
			</item>
			<item text="Ian Rankin" id="ir" ></item>
			<item text="James Patterson" id="jp" ></item>
			<item text="Nancy Atherton" id="na" ></item>
		</item>
</cf_dhtmlXTree>
</XMP>
	</div>

<a name="edititem"><h4 >Editable Items</h4></a><div class="block">
Since version 1.3 dhtmlxTree Professional got editable items. To make items text editable just 
add <em>dhtmlxtree_ed.js</em> to the page and enable this functionlity using one script line:
<XMP>
<script  src="../codebase/ext/dhtmlxtree_ed.js"></script>
<script>
	tree.enableItemEditor(mode);
</script>
</XMP>	
<strong>Parameters are:</strong>
<li><strong>mode</strong> - mandatory - true/false - enable/disable Editable items</li><br><br>

<strong>Event:</strong><br>
You can process various stages of editing item using the event handler, which can be set  
by <em>attachEvent("onEdit",handlerFunc)</em>. Event occurs on 4 different stages of edit process: 
before editing started (cancelable), after editing started, before closing (cancelable), 
after closed. The function specified as input parameter for this method will get the following arguments:<br>
<li><strong>state</strong> - 0 before editing started , 1 after editing started, 2 before closing, 3 after closed</li>
<li><strong>id</strong> - id of edited items</li>
<li><strong>tree</strong> - tree object</li>
<li><strong>value</strong> - only for stage 2, value of editor</li>

</div>

<a name="dataprocessor"><h4 >Simultaneous Server Update</h4></a><div class="block">
Common tree manipulations - like drag-n-drop (including d-n-d between trees), delete item, insert item, update item label - 
can be simultaneously reflected in server database now (since v.1.3) using dataProcessor module.<br><br>
<strong>Main features of it are:</strong><br><br>
<li>Updated/Inserted item, marked with bold text, deleted - with line-through </li>
<li>You can define the mode for data processing (automatic/manual).</li> <br>
Updated/deleted items' data sent to server to the URL you specified (we call it serverProcessor). 
serverProcessor should return simple xml of specified format (see below) 
to let tree know about successful or not successful processing. 
All necessary after-save procedures will be done automaticaly. 
<br><br>


To enable this feature you need to do the following:<br>
<li>include <em>dhtmlxdataprocessor.js</em> to the page</li>
<li>create dataProcessor object for the tree:</li>
<XMP>
<script  src="../codebase/dhtmlxdataprocessor.js"></script>
<script>
	...
	tree.init();
	myDataProcessor = new dataProcessor(serverProcessorURL);
	myDataProcessor.init(treeObj);
</script>
</XMP>	
<strong>Parameter for dataProcessor is:</strong>
<li><strong>serverProcessorURL</strong> - mandatory - url of the file which will process incomming data. 
If you use our server-side routines, then it is "dhtmlxDataProcessor/server_code/PHP/update.php?ctrl=tree", where  </li><br>
<strong>Parameter for myDataProcessor.init is:</strong>
<li><strong>treeObj</strong> - mandatory - tree object to assign dataProcessor to</li>
<br><br>
<strong>If you do not use our built-in serverProcessor</strong> and use your own file for processing 
data sent by dataProcessor you need to know the following:
<li>All data comes in GET scope:</li>
<br> - <em>tr_id</em> - node ID
<br> - <em>tr_order</em> - node sequense on the level
<br> - <em>tr_pid</em> - parent ID
<br> - <em>tr_text</em> - node text(label)
<br> - userdata blocks passed with their names<br>
<br> - !nativeeditor_status - exists and value is "inserted" for insert operation, value is "deleted" for delete, doesn't exist or value is "updated" for update operation
<li>serverProcessor should return valid XML of the following format:</li>
<XMP>
	<data>
		<action type='insert/delete/update' sid='incomming_node_ID' tid='outgoing_node_ID'/>
	</data>
</XMP>
Where <em>incomming_node_ID</em> and <em>outgoing_node_ID</em> are different for insert action only. For other actions they are equel.
<br><br>
<strong>To use unified server-side routine</strong> (available for PHP5/mySQL) do the following:<br>
<li>use "dhtmlxDataProcessor/server_code/PHP/get.php?ctrl=tree" for yourTree.loadXML(url)</li>
<li>use "dhtmlxDataProcessor/server_code/PHP/update.php?ctrl=tree" for new dataProcessor(url)</li>
<li>configure connection in dhtmlxDataProcessor/server_code/PHP/db.php</li>
<li>specify table columns in dhtmlxDataProcessor/server_code/PHP/tree_data.xml for corresponding values</li>

</div>

<a name="inithtml"><h4 >Initialize from HTML</h4></a><div class="block">
You can create tree based on html LIST or inline XML. In both cases list or xml should be incapsulated into DIV
element which will be tree container (xml should also be included into XMP tag - see code sample below). 
<br>
Any of tree mathods which start with set or enable can be used as attributes
of this DIV element to set\enable tree properties. 
<br>
Convertion can be done automatically or calling script function.

<h5>Automatic convertion</h5>
	<li>include dhtmlxtree_start.js into the page</li>
	<li>set class attribute of DIV element to dhtmlxTree</li>

<h5>Convert with script function</h5>
	<li>include dhtmlxtree_start.js into the page</li>
	<li>call dhtmlXTreeFromHTML function with id of DIV element to convert as first argument</li>
<XMP>
	var myTree = dhtmlXTreeFromHTML('listBox');
</XMP> 

<h5>Init from html List</h5>
<XMP>
	<div 
		class="dhtmlxTree" 
		id="treeboxbox_tree" 
		setImagePath="../codebase/imgs/" 
		style="width:250px; height:218px;overflow:auto;">
		
		<ul>
			<li>Root</li>
			<ul>
				<li>Child1
				<ul>
					<li>Child 1-1</li>
				</ul>
				</li>
				<li>Child2</li>
				<li><b>Bold</b> <i>Italic</i></li>
			</ul>
			</li>
		</ul>
	</div>
</XMP>

<h5>Init from inline XML</h5>
For more details about dhtmlxTree XML structure please see <a href="#xmlload">Loading data with XML</a>
<XMP>
	<div id="treeboxbox_tree2" setImagePath="../codebase/imgs/" class="dhtmlxTree" >
	<xmp>
		<item text="Root" open="1" id="11">
			<item text="Child1" select="1" open="1" id="12">
				<item text="Child1-1" id="13"/>
			</item>
			<item text="Child2" id="14"/>
			<item id="15" text="Text"/>
		</item>
	< /xmp>
	</div>
</XMP>



<h6>Version/Edition: v1.4/Professional/Standard</h6>
<h6>Required js file:dhtmlxtree_start.js</h6>
</div>

<a name="smartrnd"><h4 >Smart Rendering</h4></a><div class="block">
<p>In case your tree has big number of items per level (500 and more) you can try increasing overal performance using Smart Rendering. There is no need for any chnages in data structure - just turn it on with <i>enableSmartRendering</i> method.</p>
<h6><span class="important">Important:</span> this mode is incompatible with Distributed Parsing and Three state checkboxes.</h6>
<h6>Version/Edition: v1.5/Professional</h6>
<h6>Required js file:dhtmlxtree_srnd.js</h6>
</div>

<a name="json"><h4 >Loading from JSON</h4></a><div class="block">
To load tree from JSON you need to have JSON object or file and load it using corresponded method:
<XMP>
	tree.loadJSONObject(JSON_OBJECT);//for loading from script object
	tree.loadJSON(FILE);//for loading from file
</XMP>
<p>Both methods have second optional parameter - function to call after data was loaded.</p>

<h5>JSON format:</h5>
The structure is like <a href="#xmlload">tree XML structure</a>, where tags are transformed to objects, attributes to properties.
<xmp>
	{id:0, 
		item:[
			{id:1,text:"first"},
			{id:2, text:"middle", 
				item:[
					{id:"21", text:"child"}
				]},
			{id:3,text:"last"}
		]
	}
</xmp>

<h6>Version/Edition: v1.6/Professional/Standard</h6>
<h6>Required js file:dhtmlXGrid_json.js</h6>
</div>

<a name="csv"><h4 >Loading from CSV</h4></a><div class="block">
To load tree from CSV you need to have CSV represented as string or file and load it using corresponded method:
<XMP>
	tree.loadCSV(FILE);//for loading from file
	tree.loadCSVString(CSVSTRING);//for loading from string
</XMP>
<p>Both methods have second optional parameter - function to call after data was loaded.</p>

<h5>CSV structure:</h5>
Tree node is represented with threee values - id,parent_id,text. Like this: 
<xmp>
	1,0,node 1
	2,1,node 1.1
	3,2,node 1.1.1
	4,0,node 2
</xmp>

<h6>Version/Edition: v1.6/Professional/Standard</h6>
<h6>Required js file:dhtmlXGrid_json.js</h6>
</div>

<a name="jsarray"><h4 >Loading from JS Array</h4></a><div class="block">
To load tree from javascript array you need to have array as object or as file and load it using corresponded method:
<XMP>
	tree.loadJSArrayFile(FILE);//for loading from file
	tree.loadJSArray(ARRAY);//for loading from array object
</XMP>
<p>Both methods have second optional parameter - function to call after data was loaded.</p>

<h5>ARRAY structure:</h5>
Tree node is represented with three values as subarrays of top array - id,parent_id,text. Like this: 
<xmp>
	var treeArray = new Array(
	["1","0","node 1"],
	["2","1","node 1.1"],
	["3","2","node 1.1.1"],
	["4","0","node 2"]
	)
</xmp>

<h6>Version/Edition: v1.6/Professional/Standard</h6>
<h6>Required js file:dhtmlXGrid_json.js</h6>
</div>

<!--- 
<a name=""><h4 >...</h4></a><div class="block">
<XMP>

</XMP>
<h5></h5>
<h6>Version/Edition: v1.2/Professional/Standard</h6>
<h6>Required js file:dhtmlXGrid_start.js</h6>
</div>

 --->
</div>
<div class="copyr">&copy; DHTMLX LTD.</div>
</body>
</html>
